/**
 * Copyright 2006 gworks.com.au
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License. (http://www.apache.org/licenses/LICENSE-2.0)
 *
 * Unless required by applicable law or agreed to in writing, software distributed under the License is distributed 
 * on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for 
 * the specific language governing permissions and limitations under the License.
 *
 * <dhamma-message src="Atisha (11th century Tibetan Buddhist master)">
 * 	The greatest achievement is selflessness. The greatest worth is self-mastery.
 * 	The greatest quality is seeking to serve others. The greatest precept is continual awareness.
 * 	The greatest medicine is the emptiness of everything. The greatest action is not conforming with the worlds ways.
 * 	The greatest magic is transmuting the passions. The greatest generosity is non-attachment.
 * 	The greatest goodness is a peaceful mind. The greatest patience is humility.
 * 	The greatest effort is not concerned with results. The greatest meditation is a mind that lets go.
 * 	The greatest wisdom is seeing through appearances. 
 * </dhamma-message>
 */
package org.javaongems.client;

/**
 * <p>Provide the features of do, undo and redo.</p>
 * <p>Responsibilities:
 * <ul>
 * 	<li>support substituability with the google Command abstraction 
 * 	<li>be able to execute an instruction set
 * 	<li>undo the previously executed instruction set
 * 	<li>redo the previously undone instruction set
 * </ul>
 * </p>
 * <p>Collaborators:
 * <ul>
 * 	<li> Coordinator - for transitioned notifications
 * 	<li> Controllers - for realising the execute, undo, redo functionality
 * </ul>
 * </p>
 * <p>
 * Notes:<br/>
 * Commands are typically implemented as non-static nested classes inside
 * controllers. Thus, they are able to reference the entire state and 
 * behavior of the owning controller.
 * </p>
 * 
 * @see Coordinator#onTransition(Command)
 * @see Gem#onHistoryChanged(String)
 * @see Controller
 * 
 * @author Ashin Wimalajeewa (ash)
 */
public interface Command extends com.google.gwt.user.client.Command {
	/**
	 * Command that undoes the previously executed "execute()" method. This method
	 * is invoked by the Coordinator when it receives the back signal
	 * from the browser.
	 * 
	 * @see Coordinator#back()
	 * @see Coordinator#onTransition(Command)
	 * @see #execute()
	 * @see #redo()
	 */
	public void undo();
	
	/**
	 * Command that repeats a previously executed "execute()" method after the undo() 
	 * method was invoked. This method is invoked by the Coordinator when it receives 
	 * the forward signal from the browser.
	 * 
	 * @see Coordinator#forward()
	 * @see Coordinator#onTransition(Command)
	 * @see #execute()
	 * @see #undo()
	 */
	public void redo();
}
